In LISTSERV Maestro, calculation formulas are currently available in the context of the special
*Calc system drop-in, in the condition tree of target groups of type "Dataset" or "Hosted Recipient List", and in the derivation rule of a derived profile field in a dataset or hosted recipient list. The syntax and semantics of these calculation formulas are described here.
A formula is a sequence of expressions that are combined with operators into more complex expressions. Expressions can be optionally nested with parenthesis and make use of a few pre-defined functions.
|
•
|
Number – The value is an integer number in the following range:
|
|
•
|
Text – The value is a character string that may contain any sequence of characters, including an empty sequence.
|
|
•
|
Boolean – The value is a boolean value, either true or false.
|
|
•
|
Number Set – The value is a set of numbers that is a collection of distinct values of the type number. That is, each number can be contained only once. The set can either have no elements (an empty set), single elements, or any number of elements.
|
|
•
|
Text Set – The value is a set of text strings. Similar to a number set, a text set is a collection of distinct values of the text type that can have zero, one, or several elements.
|
Operators and functions usually require their operands and arguments to be of a certain type. However, under some circumstances it is possible to supply an expression of a different type as an operand or argument, which will then automatically be converted to the required type.
|
•
|
Automatic conversion to Text – Whenever an operand or argument of type Text is required, an expression either of type Text or of type Number can be supplied. In the latter case, the number will then first be converted into a text before the operator or function is applied. For this conversion, the number-value is simply converted into the corresponding string representation, for example the number 157 becomes the text string "157".
|
|
•
|
Automatic conversion to Number Set – Whenever an operand or argument of type Number Set is required, an expression either of type Number Set or of type Number can be supplied. In the latter case, the number will then first be converted into a number set with a single element, before the operator or function is applied.
|
|
•
|
Automatic conversion to Text Set – Whenever an operand or argument of type Text Set is required, an expression either of type Text Set, Number Set, Text or Number can be supplied. In the latter cases, a conversion to Text Set will be performed before the operator or function is applied:
|
Restriction: None. Constant number expressions can be used in any formula.
Type: Constant number expressions are, as the name implies, always of the
number type.
Usage: To include a constant number in a formula, simply type the number using only the digits “
0“-“
9” (do not use “
,” as a thousands-separator or “
.” as a decimal point). Negative numbers must have a leading minus sign “
-“.
Restriction: None. Constant text literal expressions can be used in any formula.
Type: Constant text literal expressions are, as the name implies, always of the
text type.
Usage: To include a text literal in a formula, type the characters desired and denote the beginning and the end of the text literal by enclosing the whole string in quotation marks <
">. There must not be any line breaks in the text string.
"example"
"this is a text string"
"This string contains ""quotes"" which are therefore escaped"
" this string has three spaces at the beginning and end "
Restriction: None. Constant boolean expressions can be used in any formula.
Type: Constant boolean expressions are, as the name implies, always of type Boolean.
Usage: To include a constant boolean in a formula, simply type either "true" or "false" (without the quotes).
Restriction: Standard merge field expressions are only allowed if the formula is used in one of the following contexts:
|
•
|
In a *Calc system drop-in of a job with the following recipient types:
|
If the system drop-in is used in a job with a different recipient type, the formula must not contain any merge field expressions. If it does, an error message will be displayed about this during test delivery.
Type: Standard merge field expressions can be of type Number, Text, Boolean or Text Set, depending on their context and content (see "Type Determination" below for details).
Usage: To include a standard merge field in a formula, type the merge field name enclosed in (&) and (;). Only use merge field names that are actually defined in the recipient list.
Type Determination: Whenever any such merge field appears in a formula, it will first be replaced with the field value for the current recipient. This occurs before the result of the formula is calculated for that recipient. To be able to do this calculation, the expression's type is determined as follows:
|
•
|
If the formula is used in a *Calc system drop-in with the recipients types "uploaded CSV text file" or "LISTSERV Maestro selects from a database", then the type of the field is determined by the field's content as follows:
|
Special Note for "Datasets" and "Hosted Recipient Lists": If the formula is used in the condition tree of a "Dataset" or "Hosted Recipient List" target group or in a
*Calc system drop-in together with recipients based on such a target group, then there are special rules for profile fields of type "Number" or "Text". If such a profile field is defined in the dataset or hosted recipient list as "optional" then this field can not be used in a "standard merge field" expression. Instead, use the "optional merge field" expression instead (see next section.)
Restriction: Optional merge field expressions are only allowed if the formula is used in one of the following contexts:
|
•
|
In a *Calc system drop-in of a job with the following recipient types:
|
If the system drop-in is used in a job with a different recipients type, the formula must not contain any merge field expressions. If it does, an error message will be displayed about this during test delivery.
Type: Optional merge field expressions can either be of type Number" or of type Text, depending on their context and content (see "Type Determination" below for details).
Usage: Optional merge fields are fields that may be undefined (empty) for at least some recipients in the recipient list. If such a field would be used normally in a formula, it would not be possible to calculate the result of the formula for those recipients. Therefore, such "possibly undefined" fields must be included as "optional merge field" expressions, not as "standard merge field" expressions. An optional merge field expression is written in the following way:
The whole expression must be enclosed in brackets "[" and "]". Between the brackets the name of the merge field to be addressed appears first, enclosed with (&) and (;), then the default content that will be used for all recipients where the merge field itself is undefined.
Note: The second example defines an empty text as the default for
&NAME;.
Type Determination: Whenever any such merge field appears in a formula, it will first be replaced with the field value for the current recipient, or if that value is undefined or empty, it will be replaced with the given default. Next, the result of the formula is calculated for that recipient. To be able to do this calculation, the expression's type is determined just like for "standard merge field" expressions.
In addition, if the field's value is empty or undefined, the type will be determined by the type of the given default. Therefore, make sure that the type of the default matches the field's type or is at least convertible to that type.
Special Note for "Datasets" and "Hosted Recipient Lists": If the formula is used in the condition tree of a "Dataset" or "Hosted Recipient List" target group or in a
*Calc system drop-in together with recipients based on such a target group, then only profile fields of type "Number" or "Text" can be used in an "optional merge field" expression, and also only if that field is actually defined as "optional". For fields of other types, or for fields that are defined as "mandatory", use the "standard merge field" expression instead (see previous section.)
Restriction: Functions can usually be used in any formula. However, there may be individual restrictions that apply only to certain functions. See the function descriptions for details.
Type: The type depends on each function. See the function descriptions for details.
Usage: To include a function in a formula, simply type the function name possibly followed by an argument list in parenthesis. See the function description for details concerning whether arguments are required by a certain function and what they mean. Note that function names are case sensitive and that any parenthesis enclosing the argument list must immediately follow the function name, without any space in between.
Abs(-20)
Max(15, &AGE;)
ToLower("Convert this string to ALL Lowercase")
Min(-10, -11, &SIZE_A;, &SIZE_B;)
Available Functions: The currently available functions are described in
Formula Functions.
Restriction: Target group parameter expressions are only allowed if the formula is used in the condition tree of a "Dataset" or "Hosted Recipient List" target group. They must not be used in a formula of a
*Calc system drop-in.
Type: Either Number or Text, depending on how the parameter is specified (see below).
Usage: A target group parameter is a parameter that is specified during target group definition, but whose value is not yet known at that time. The parameter will later be "filled out" with content by a user choice made in the recipients wizard, when the target group is used for recipient definition.
To include a target group parameter in a formula, simply type the name of the parameter enclosed in double curly brackets "{{" and "}}". The parameter name must only contain the characters "A" to "Z", "a" to "z", "0" to "9" and the underscore "_".
If a parameter is enclosed with quotes (") like a text string, its content is interpreted as Text. If it is not enclosed in quotes, its content is interpreted as Number, so it is important to make sure that all possible parameter values are indeed valid numbers (for type "number").
Notes: If you include the same parameter name several times in the same formula, it will be interpreted as one parameter that simply appears several times. All appearances will have the same content value and must also all appear in the same type context as Number or Text and they must either all be enclosed in quotes to be interpreted as Text parameters, or none of them must be enclosed in quotes (to be interpreted as Number).
Similarly, if a parameter is used with the same name in the same target group but outside of a formula or in a different formula, then all these appearances of the parameter name (in the same target group) will reference the same parameter. All of them will be replaced with the same final content during usage in the recipients wizard.
Note: In LISTSERV Maestro, division is strictly an integer division; therefore, any decimal places in the result are discarded (not rounded off, but simply ignored).
Notes: If only one operand is of the Text type and the other is of the Number type, then this number operand will automatically be converted into a text before the operator is applied.
Text comparisons are case sensitive, so "this" is not equal to "THIS".
Also the "less-than" and "greater-than" comparisons are based on the character ordering of the Unicode standard, which makes a difference between lowercase and uppercase characters. For example, even though "ABC" < "XYZ" is true, "abc" < "XYZ" is not true, because in Unicode all uppercase characters come before all lowercase characters.
If you need to perform a case insensitive comparison, you should first convert both operands to the same case (either lowercase or uppercase) using the "ToLower(arg)" or "ToUpper(arg)" functions.
If only one operand is of type Set and the other is of type Text or Number, or if both operands are sets, but one is of type Number Set and the other of type Text Set, then the following conversion will automatically be performed before the operator is applied:
|
•
|
One operand is of type Text Set: Depending on the type of the other operand, one of the following conversions may be performed:
|
|
•
|
Number – The number operand is converted into a text set by creating a new set with a text representation of the number as the single element of the set. After this, both operands are of type Text Set and the set operator can be applied to them.
|
|
•
|
Text – The text operand is converted into a text set by creating a new set with the text as the single element of the set. After this, both operands are of type Text Set and the set operator can be applied to them.
|
|
•
|
Number Set – The number set operand is converted into a text set by creating a new set that contains text representations of all numbers in the number set. After this, both operands are of type Text Set and the set operator can be applied to them.
|
|
•
|
Text Set – No conversion necessary. Both operands are of type Text Set anyway and the set operator can be applied to them.
|
|
•
|
One operand is of type Number Set: If the other operand is of type Text Set, then we are dealing with a case that was already described above. If the other operand is not of type Text Set, then depending on the type of the other operand, one of the following conversions may be performed:
|
|
•
|
Number – The number operand is converted into a number set by creating a new set with the number as the single element of the set. After this, both operands are of type Number Set and the set operator can be applied to them.
|
|
•
|
Text – The text operand is converted into a text set by creating a new set with the text as the single element of the set. In addition, the Number Set argument itself is also converted into a text set by creating a new set that contains text representations of all numbers in the number set. After this, both operands are of type Text Set and the set operator can be applied to them.
|
|
•
|
Number Set – No conversion necessary. Both operands are of type Number Set anyway and the set operator can be applied to them.
|
Operators with higher precedence are processed first. If several operators with the same precedence level are encountered, they are processed from left to right. Parenthesis can be set freely to influence precedence where inner parenthesis will be processed before outer parenthesis.
15 + 3 * 4 Result: 27
8 * (7 - 3) Result: 32
17 * 22 / 2 % 5 Result: 2
17 * (22 / 2 % 5) Result: 17
17 * (22 / (2 % 5)) Result: 187
|
•
|
Abs – Converts a number into its absolute (non-negative) number.
|
|
•
|
IsNum – Checks if the given argument can be converted into a number.
|
|
•
|
Max – Finds the largest of several numbers.
|
|
•
|
Min – Finds the smallest of several numbers.
|
|
•
|
Pow – Raises a number to a specified power.
|
|
•
|
Random – Generates a random number.
|
|
•
|
ToNum – Converts any non-number data type into a number.
|
|
•
|
Contains – Checks if one text contains another.
|
|
•
|
EndsWith – Checks if a text ends with a certain text suffix.
|
|
•
|
HTMLEncode – Encodes all HTML-unsafe characters in a text.
|
|
•
|
EndsWith – Finds the first (or next) occurrence of one text in another.
|
|
•
|
LastIndexOf – Finds the last (or previous) occurrence of one text in another.
|
|
•
|
Length – Determines the length of a text.
|
|
•
|
Matches – Determines if a text matches a certain "regular expression".
|
|
•
|
ReplaceText – Replaces all occurrences of a certain sub-string in a text with a new string.
|
|
•
|
Substring – Extracts a specified substring from a text.
|
|
•
|
StartsWith – Checks if a text starts with a certain text prefix.
|
|
•
|
ToLower – Converts a text into all lowercase.
|
|
•
|
ToUpper – Converts a text into all UPPERCASE.
|
|
•
|
Trim – Trims leading and trailing whitespace from a text.
|
|
•
|
URLEncode – Encodes all URL-unsafe characters in the text.
|
|
•
|
If – Evaluates a condition and determines one of two possible values as a result.
|
|
•
|
Count – Counts all elements in a set.
|
|
•
|
In – Determines if a set contains a certain element.
|
|
•
|
SetOf – Builds a set out of a list of elements.
|
|
•
|
SetToString – Converts a set into a string by listing all elements in the set.
|
|
•
|
SetToStringWithMaxLen – Converts a set into a string (with a maximum length) by listing all elements in the set.
|
|
•
|
CurrentMillis – Determines the current date/time, in milliseconds.
|
|
•
|
IsDate – Checks if a textual date/time representation is valid.
|
|
•
|
SubscribeTimeMillis – Determines the subscription date/time of a hosted subscriber, in milliseconds.
|
|
•
|
ToDate – Converts a milliseconds time value into a textual date/time representation.
|
|
•
|
ToMillis – Converts a textual date/time representation into a milliseconds time value.
|
|
•
|
IsSupplied – Checks if a certain merge field has a value or not.
|
|
•
|
SecondaryValue – Retrieves the secondary values for a single/multiple select profile field.
|
Function: Returns the absolute value of the given Number or Number Set argument.
Return-Type: Number or Number Set
|
•
|
arg - This argument can be of type Number or Number Set and its absolute value is to be determined. If a single number is given, then the absolute value of that number is returned. If a set of numbers is given, then a Number Set is returned that contains the absolute values of all numbers in the argument set.
|
Abs(-10)
Abs(&VALUE;)
Abs(30 - &ACCOUNT; * 2)
Abs(SetOf(10, -333, 15, &VALUE1;, &VALUE2;))
Function: Checks if the given argument can be converted into a number or set of numbers. Returns "true" if the argument can be converted into a number or set of numbers, "false" if not.
This function is a companion function to “ToNum”: If
IsNum returns "true" for a given argument, then it is safe to use
ToNum on the same argument (i.e.
ToNum will not generate an error when used with the same argument).
|
•
|
arg - This argument can be of any type:
|
|
•
|
Text: The text is parsed and an attempt is made to convert it into a number. If this is successful, then "true" is returned, otherwise "false".
|
|
•
|
Text Set: All elements in the set are parsed and converted into numbers. If this is successful for all elements in the set, then "true" is returned, otherwise "false".
|
|
•
|
Boolean: Always results in a return value of "true".
|
Function: Returns the greatest of all given Number arguments.
|
•
|
arg1 - This argument can be of type Number or Number Set, and its the first argument to find the maximum of. (Further arguments are optional.)
|
|
•
|
arg2 - This argument can be of type Number or Number Set, and its the second argument to find the maximum of.
|
|
•
|
argN - This argument can be of type Number or Number Set and is the Nth argument to find the maximum of. If any of the arguments are a set of numbers, then the maximum will be determined over all numbers in this set (and any other arguments, if present).
|
Function: Returns the smallest of all given Number arguments.
|
•
|
arg1 - This argument can be of type Number or Number Set, and its the first argument to find the minimum of. (Further arguments are optional.)
|
|
•
|
arg2 - This argument can be of type Number or Number Set, and its the second argument to find the minimum of.
|
|
•
|
argN - This argument can be of type Number or Number Set, and its the Nth argument to find the minimum of. If any of the arguments is a set of numbers, then the minimum will be determined over all numbers in this set (and any other arguments, if present).
|
Function: Returns the value of the first argument raised to the power of the second argument.
|
•
|
base - This argument can be of type Number, and its the base argument.
|
|
•
|
exp - This argument can be of type Number, and its the exponent argument.
|
Function: Returns a pseudo-random number in a range specified by the argument. If no argument is given, then the range is from 0 to the largest possible Number value. If one argument given, then the range is from 0 to the value of the given argument minus one (i.e. "0" to "arg-1").
Arguments: (The argument is optional)
|
•
|
threshold - This argument can be of type Number, and its the threshold value for the random number. The random number will range from "0" to "threshold - 1".
|
Random
Random(6)
Random(&MAX_RANDOM;)
Random(&VALUE; - 17 * &MAX;)
Function: Tries to convert the given argument into a number or set of numbers. It generates a runtime error if that is not possible (for example, if the argument is a text that contains characters that are not part of a number representation, like letters). If you are unsure if a certain argument can be converted into a number without an error, and you want to avoid this error, then use the companion function
IsNum to first check if the argument can be converted at all, together with the function
If.
This function can, for example, be used to convert a profile field of type Text, which only contains numbers, to the type Number, which can then be used in contexts that require the type Number (such as number operators and functions that require a number argument).
Return-Type: Number or Number Set
|
•
|
arg - This argument can be of any type:
|
|
•
|
Text: The text is parsed and an attempt is made to convert it into a number. This is possible if the text contains only digits and optionally a leading minus sign (otherwise an error is generated). A single number is returned.
|
|
•
|
Text Set: All elements in the set are parsed and converted into numbers (if possible, otherwise an error is generated). A Number Set that contains all these numbers is returned.
|
|
•
|
Boolean: The boolean value "true" is converted into the number "1", the boolean value "false" is converted into the number "0". This number is then returned.
|
ToNum("12345")
ToNum(&AGE;)
ToNum(true)
ToNum("123" + "456")
If(IsNum(&TEXTFIELD;), ToNum(&TEXTFIELD;), 0)
Notes: The result of the second-to-last example will not be the number 579, but will instead be the number 123456. The string concatenation operator "+" is first applied to the two text strings and then the resulting string is converted into a number.
The last example shows how ToNum is used together with
IsNum and If, to make sure that no runtime error is generated: If the field TEXTFIELD contains a number, then this number is supposed to be used. If not, then instead the default of "zero (0)" is to be used. So the result of this If function is in turn a number: Either the number that was parsed from TEXTFIELD, or the number "0". Thus, the result of the If function can safely be used in a context where a Number type is required, without fearing a runtime error if TEXTFIELD should contain a non-number text.
Function: Checks if "text" contains an appearance of "searchfortext". It returns "true" if the text is found, "false" if not.
|
•
|
text - This argument can be of type Text, and its the text string to search in.
|
Function: Checks if "text" ends with the given "suffix", i.e. if the last characters in "text" are equal to the characters in "suffix". Returns "true" if the suffix matches, "false" if not.
|
•
|
text - This argument can be of type Text, and its the text string whose suffix is to be checked.
|
|
•
|
suffix - This argument can be of type Text, and its the suffix to check for.
|
Function: Returns the given text argument (or set of texts) with the following characters which are unsafe to use in a HTML context encoded into HTML entities, so that the resulting text can be safely included in a HTML context:
Return-Type: Text or Text Set
|
•
|
arg - This argument can be of type Text or Text Set. If a single text is given, then this text is encoded and the result is returned. If a set of texts is given, then all texts in the set will be encoded and a set with these encoded texts is returned.
|
Function: Searches for an occurrence of the text "searchfortext" in the given "text". Returns the zero-based index of the first occurrence of "searchtext", or "-1" if none was found. Optionally a zero-based "startindex" can be specified with the effect that the search in "text" will not start at the beginning of "text" but at the character position specified by "startindex".
|
•
|
text - This argument can be of type Text, and its the text string to search in.
|
|
•
|
searchfortext - This argument can be of type Text, and its the string to search for.
|
|
•
|
startindex - This argument can be of type Number, and its the character position at which the search will be started. If not given, the search will always start at the first character (index "0"). This argument is optional.
|
Function: Searches for an occurrence of the text "searchfortext" in the given "text", starting at the end of "text". Returns the zero-based index of the last occurrence of "searchtext", or "-1" if none was found. Optionally a zero-based "startindex" can be specified with the effect that the search in "text" will not start at the end of "text" but at the character position specified by "startindex" (and then proceed towards the start of "text").
|
•
|
text - This argument can be of type Text, and its the text string to search in.
|
|
•
|
searchfortext - This argument can be of type Text, and its the string to search for.
|
|
•
|
startindex - This argument can be of type Number, and its the character position at which the search will be started. If not given, the search will always start at the last character (index "length - 1"). This argument is optional.
|
Function: Returns the length of the given text string (the number of characters in the text).
|
•
|
text - This argument can be of type Text, and its the text whose length shall be determined.
|
Function: Checks if "text" matches the regular expression in "regexp". Returns "true" if the text matches, "false" if not.
A regular expression, which can be seen as a "pattern", is an expression that describes a set of texts. With this expression, the desired set can be described without having to list all elements. Therefore, The
Matches function actually does nothing else than to check if the given "text" is among the set of texts that is defined by the regular expression in "regexp".
To be able to describe a whole set of texts with a single expression, regular expressions make intensive use of special character constructs, like for example wildcards, quantifiers, boundary matchers and others. The topic of regular expressions is a very wide field. For the regular expression constructs that are supported by LISTSERV Maestro, please see the online help.
|
•
|
text - This argument can be of type Text, and its the text string to match.
|
|
•
|
regexp - This argument can be of type Text, and it the regular expression to use.
|
Function: Searches for all occurrences of "oldtext" in the given "arg" and replaces these occurrences with "newtext". If "arg" is a single text, then the replacement is performed in this text and the result is returned. If "arg" is a Text Set, then the replacement is performed individually on all texts in the set and the resulting set is returned.
Return-Type: Text or Text Set
|
•
|
arg - This argument can be of type Text or Text Set, and its the text (or set of texts) to search in.
|
|
•
|
oldtext - This argument can be of type Text, and its the text that will be replaced.
|
|
•
|
newtext - This argument can be of type text, and its the text that will replace all occurrences of "oldtext".
|
Function: Returns a text substring that has been extracted from the given original text string according to the other argument(s) as specified:
If no "endindex" is given, the substring extends to the end of the original string. If "endindex" is given, the substring extends to the character at position "endindex - 1" (i.e. the character at "endindex" is the first character that is not part of the substring).
Note: All indices are zero-based. The index of the last character in the original string is at the position "length of original string minus 1".
|
•
|
originaltext - This argument can be of type Text, and its the original text string from which the substring will be extracted.
|
|
•
|
startindex - This argument can be of type Number, and its the beginning index, inclusive, zero-based.
|
|
•
|
endindex - This argument can be of type Number, and its the ending index, exclusive, zero-based. This argument is optional.
|
Function: Checks if "text" starts with the given "prefix", i.e. if the first characters in "text" are equal to the characters in "prefix". Returns "true" if the prefix matches, "false" if not.
|
•
|
text - This argument can be of type Text, and its the text string whose prefix is to be checked.
|
|
•
|
prefix - This argument can be of type Text, and its the prefix to check for.
|
Function: Returns the given text argument (or set of texts) with all letters converted to lowercase letters.
Return-Type: Text or Text Set
|
•
|
arg - This argument can be of type Text or Text Set. If a single text is given, then this text is converted to lowercase and the result is returned. If a set of texts is given, then all texts in the set will be converted to lowercase and a set with these converted texts is returned.
|
Function: Returns the given text argument (or set of texts) with all letters converted to UPPERCASE letters.
Return-Type: Text or Text Set
|
•
|
arg - This argument can be of type Text or Text Set. If a single text is given, then this text is converted to uppercase and the result is returned. If a set of texts is given, then all texts in the set will be converted to uppercase and a set with these converted texts is returned.
|
Function: Trims leading and trailing whitespace from the given text argument (or set of texts), i.e. returns a text (or set of texts) where all leading and trailing whitespace has been removed. This functions interprets all characters with an ASCII-value of 32 (20h) or lower as whitespace.
Return-Type: Text or Text Set
|
•
|
arg - This argument can be of type Text or Text Set. If a single text is given, then this text is trimmed and the result is returned. If a set of texts is given, then all texts in the set will be trimmed and a set with these trimmed texts is returned.
|
Function: Returns the given text argument (or set of texts) with all characters that are unsafe to be used in a URL parameter encoded in URL-safe form, so that the resulting text can be safely included in a URL or as a URL parameter.
Return-Type: Text or Text Set
|
•
|
arg - This argument can be of type Text or Text Set. If a single text is given, then this text is encoded and the result is returned. If a set of texts is given, then all texts in the set will be encoded and a set with these encoded texts is returned.
|
Function: Evaluates the "condition" and returns either the "value1" (if the condition is "true") or the "value2" (if the condition is "false").
Return-Type: Depends on "value1" and "value2" (see below).
|
•
|
condition - This argument can be of type Boolean, and its the condition to evaluate.
|
|
•
|
value1 - This argument can be of any type (see below), and its the value to return if the condition evaluates to "true".
|
|
•
|
value2 - This argument can be of any type (see below), and its the value to return if the condition evaluates to "false".
|
Note: Even though "value1" and "value2" can be of any type, the types of these two values must either be the same, or one type must be convertible into the other. If both types are the same, then this is also the return type of the function. If the types are different, but one type can be converted into the other type, then this other type is the return type of the function (even if the value with the first type should be selected by the condition). For details on conversions, see
Automatic Type-Conversion.
Function: Counts and returns the number of elements in the given set.
|
•
|
set - This argument can be of type Text Set or Number Set, and its the set to count the elements of.
|
Function: Checks if the given "element" is contained in the given "set". Returns "true" if the element is found in the set, or "false" if not.
|
•
|
element - This argument can be of type Number or Text, and its the element to look for.
|
|
•
|
set - This argument can be of type Number Set or Text Set, and its the set to search in.
|
Function: Returns a set that contains all arguments. If some arguments are also sets, then the resulting set will contain all elements from these sets individually (i.e. the resulting set will not contain the other sets themselves as its elements, but rather will contain all elements from these other sets). If no argument is given at all, then an empty set is returned.
Return-Type: Number Set or Text Set, depending on the arguments (see below).
Arguments: (All arguments are optional)
|
•
|
arg1 - This argument can be of any type, except Boolean. The first element to include in the result set.
|
|
•
|
argN - This argument can be of any type, except Boolean. The Nth (and last) element to include in the result set.
|
If any of the arguments is of type Text or Text Set, then the resulting set will also be a Text Set. If all arguments are either of type Number or Number Set, then the resulting set will be a Number Set. Arguments of type Boolean are not allowed.
SetOf(3, 19882, -4, 3371)
SetOf("abc", "def", "ghi")
SetOf("abc", 15, SetOf("xyz", "qvw"), 28, "def")
SetOf(&VALUE1;, "xyz", &MULTI_SELECT_FIELD;)
Function: Converts a set into a text string by listing all values in the set (if any), separating them with a specified separator character and optionally also enclosing the values in specified delimiters.
Important: The final result of a formula in a
*Calc system drop-in must not exceed the maximum length of 900 characters. Similarly, if the formula is used in the derivation rule of a derived profile field (in a dataset or hosted list), then the result must not exceed the maximum length of 100 characters. Using
SetToString in a formula does increase the danger of exceeding these limits, especially if the result of the function is also used as the direct result of the formula (without further processing by other functions), and if the set contains a large number of values (e.g. this may easily be the case if the set is defined by a multiple-select merge field). In such a situation, the mail job delivery may fail (if used in a
*Calc system drop-in) or the recalculation of the derived profile field may fail (if used in a derivation rule). If in doubt, it may be better to use the
SetToStringWithMaxLen function instead, which allows you to control the output length of the result. If the formula is used in the condition tree of a "Hosted Recipient List" target group, then such a restriction does not apply.
|
•
|
set - This argument can be of type Number Set or Text Set, and its the set that is to be converted into a text.
|
|
•
|
default - This argument can be of type Text, and it defines the default text that shall be the result of the function if the given set is empty. If not specified, then an empty text string is used as the result for an empty set. This argument is optional.
|
|
•
|
separator - This argument can be of type Text, and its the separator text that is to appear between two values. The separator will only appear between values, i.e. it will not appear before the first or after the last value. So if the set has less than two elements, the separator will not appear at all. Note, that "separator" may be any text, not only a single character. If not specified, the comma "," is used by default as the separator. This argument is optional but may be supplied if the "default" argument has been supplied too.
|
|
•
|
delimiter - This argument can be of type Text, and its the delimiter text that is to be used to enclose values. In some situations, it may happen that the values from the set already contain the chosen "separator" as part of their value texts. In such a case, the occurrences of the separator text in the values may be confusing, as such an occurrence may be misinterpreted as an actual separator, after which a new value starts, while it actually is only part of the value. To avoid this, it is possible to enclose the values in delimiters, to better mark the beginning and end of a value (if such a value then contains the separator text, then this does not matter, as the end of the value is no longer marked by the separator, but instead by the delimiter). For this, the "delimiter" argument can be used. If specified, then individual values may be enclosed in the specified delimiter text (depending on the "delimitAll" argument, see below). If a value is enclosed with delimiters, and the value itself also already contains the delimiter text, then this delimiter text is escaped (in a way depending on the "delimiterEscape" argument, see below). Note that "delimiter" may be any text, not only a single character. If not specified, then values are never enclosed with extra delimiters. This argument is optional but may be supplied if the "default" and "separator" arguments have been supplied too.
|
|
•
|
delimitAll - This argument can be of type Boolean. If set to "true", then all values will be enclosed with the given delimiter text. If set to "false", then only values that actually contain the separator text will be enclosed with delimiters. If not specified, then all values will be enclosed with delimiters (default is "true"). This argument is optional but may be supplied if the "default", "separator" and "delimiter" arguments have been supplied too.
|
|
•
|
delimiterEscape - This argument can be of type Text, and it defines which text will be used to escape an occurrence of the delimiter text in a value. If a value is enclosed with delimiters, but the value already contains the delimiter text itself, then this contained delimiter text could be confused with the end-delimiter, that ends the value. Therefore, if the delimiter text appears in the value, it needs to be "escaped". The escaping is done by inserting the "delimiterEscape" text just before the delimiter text in the value. If "delimiterEscape" is not specified, then the delimiter text itself will be used for escaping, i.e. this has the effect, that if the delimiter text appears in the value, then it will be escaped by doubling it. For example: If the delimiter text is the standard quote character <">, and the value already contains quotes, like this: <value "contains" quotes>. And if no "delimiterEscape" is specified, so that the default is applied, then the escaped value will contain "doubled" quotes, like this: <value ""contains"" quotes>. If instead for example the backslash is supplied for "delimiterEscape", then the escaped value will look like this: <value \"contains\" quotes>. Note that "delimiterEscape" may be any text, not only a single character. This argument is optional but may be supplied if the "default", "separator", "delimiter" and "delimitAll" arguments have been supplied too.
|
SetToString(&MULTI_SELECT_FIELD;)
SetToString(&MULTI_SELECT_FIELD;, "empty")
SetToString(&MULTI_SELECT_FIELD;, "empty", "; ")
SetToString(&MULTI_SELECT_FIELD;, "empty", "; ", "'")
SetToString(&MULTI_SELECT_FIELD;, "", "; ", "'", false)
SetToString(&MULTI_SELECT_FIELD;, "", "; ", "'", true, "\")
Function: This is a specialized version of the
SetToString function.
SetToStringWithMaxLen also converts a set into a text string, but observes a given maximum text length, by listing only so many values from the set as may fit into the maximum length. Similarly to
SetToString, the values are separated with a specified separator character and optionally enclosed in the specified delimiters. If not all values fit the maximum length, then optionally an omission text may be appended.
The SetToStringWithMaxLen function is useful if you want to make sure that the final output length of the converted set does not exceed a certain limit. For example the maximum of 900 characters if the formula is used in a
*Calc system drop-in, or 100 characters if the formula is used in the derivation rule of a derived profile field.
|
•
|
set - This argument can be of type Number Set or Text Set, and its the set that is to be converted into a text.
|
|
•
|
maxlen - This argument can be of type Number, and its the maximum length for the resulting text. If a positive "maxlen" is supplied, then the returned text will never be longer than this value (although it may be shorter if there are not enough elements in the set). If "0" or a negative "maxlen" is supplied, the returned text will always be an empty text string.
|
|
•
|
omissionText - This argument can be of type Text: If at least one of the elements from the set has to be left out from the enumeration because of the specified "maxlen", then this "omissionText" will be appended to the resulting text, to signify that some values have been left out. this argument is optional.
|
Note: The length of the omission text also counts against the given maximum length. So if an omission text is to be appended (because some values have been left out), but with the omission text the result would then be too long, then even more values will be left out, until there is enough space to fit in the omission text too. If you do not want an omission text to appear at all, then specify an empty text string "" for this argument.
Special Feature: If inside of the omission text you specify the placeholder #COUNT (with this exact spelling, in all UPPERCASE), then this placeholder will be replaced with the number of omitted elements before the omission text is appended. So if you for example specify the text "and #COUNT more", and in the result twelve elements have been omitted, then the omission text in the result will read "and 12 more". If not specified, then "..." is used as the default omission text. The remaining arguments "default", "separator", "delimiter", "delimitAll" and "delimiterEscape" work exactly as with the
SetToString function. Please see there for details. These arguments are optional but may be supplied if the "omissionText" argument has been supplied too.
SetToStringWithMaxLen(&MULTI_SELECT_FIELD;, 100)
SetToStringWithMaxLen(&MULTI_SELECT_FIELD;, 100, " and more...", "empty")
SetToStringWithMaxLen(&MULTI_SELECT_FIELD;, 200, " and #COUNT more...", "empty", "; ")
SetToStringWithMaxLen(&MULTI_SELECT_FIELD;, 200, "", "empty", "; ", "'")
SetToStringWithMaxLen(&MULTI_SELECT_FIELD;, 200, "", "", "; ", "'", false)
SetToStringWithMaxLen(&MULTI_SELECT_FIELD;, 200, "", "", "; ", "'", true, "\")
Function: Returns the current time, in milliseconds since "Jan. 1st 1970, 00:00:00 GMT".
Function: Checks if the given format specifications can be used to correctly parse a numerical date/time value from the given "datetext" text argument. Returns "true" if a date/time value can be correctly parsed from the arguments, "false" if not.
This function is a companion function to ToMillis. If
IsDate returns "true" for a given set of arguments, then it is safe to use
ToMillis on the same set of arguments (i.e.
ToMillis will not generate an error when used with the same arguments).
Please see Date and Time Patterns for details about how to write the format pattern.
Note: For formatting purposes, LISTSERV Maestro will by default use the U.S. locale and the time zone of the server where the LUI component is running. Therefore, locale specific texts, like weekday names, names of months, and so on, will be formatted using the U.S. locale. Similarly, times will be formatted using the server's time zone. If you want to specify a different locale, you can do so with the optional parameter "localename" to choose a predefined locale or with the optional parameters "langcode" and "countrycode" to specify your own locale. See
Predefined Locales for details. If you want to specify the time as relative to a different time zone, you can include a time zone value in the date/time text.
|
•
|
datetext - This argument can be of type Text, and its the date/time text string to parse. Must contain the desired date/time in a textual format that can be parsed by applying the given format pattern.
|
|
•
|
formatpattern - This argument can be of type Text, and it specifies the format pattern to use to parse the "datetext".
|
|
•
|
localename - This argument can be of type Text, and its the name of a predefined locale. If specified, any locale specific text in "datetext" will be expected according to this locale. This argument is optional. Either you supply no further argument at all or you only supply this argument.
|
|
•
|
langcode - This argument can be of type Text, and its a lowercase two-letter ISO-639 language code specifying the language for the locale. For example, see here http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt for one list of the ISO-639 language codes. This argument is optional. Either you supply no further argument at all or you supply both the following this argument and the next.
|
|
•
|
countrycode - This argument can be of type Text, and its an uppercase two-letter ISO-3166 country code specifying the country for the locale. For example, see here http://www.iso.org/iso/country_codes/iso_3166_code_lists.htm for one list of the ISO-3316 country codes. If "langcode" and "countrycode" are specified, they are used to create a locale for the given language and country, and any locale specific text in "datetext" will be expected according to this locale.
|
IsDate("February 22. 2004", "MMMM dd. yyyy")
(parses the given date using the default U.S. locale)
IsDate("Februar 22. 2004", "MMMM dd. yyyy", "Germany")
(parses the given date using the pre-defined locale for Germany)
IsDate("februari 22. 2004", "MMMM dd. yyyy", "de", "AT")
(parses the given date using a custom locale for language "de" =German and country "AT" =Austria)
Function: Returns the time when the subscriber has joined the dataset or subscribed to the hosted recipient list which is referenced by the target group in whose context the formula is used, represented in milliseconds since "Jan. 1st 1970, 00:00:00 GMT".
Restriction: Can only be used in formulas in the condition tree of a "Dataset" or "Hosted Recipient List" target group or in a
*Calc system drop-in together with recipients based on such a target group. Will not be accepted in formulas for a different recipients type or in a formula of a derivation rule (of a derived profile field in a dataset or hosted list)!
Function: Returns a formatted representation of a numerical date/time value. The formatted representation is usually returned as type Text, but may also be returned as type Number, if applicable. The format that is used to create the representation is specified with the given format argument.
Note: For formatting purposes, LISTSERV Maestro will, by default, use the U.S. locale and the time zone of the server where the LUI component is running. Therefore, locale specific texts, like weekday names, names of months, and so on, will be formatted using the U.S. locale. Similarly, times will be formatted using the server's time zone. If you want to specify a different locale, you can do so with the optional parameter "localename" to choose a predefined locale or with the optional parameters "langcode" and "countrycode" to specify your own locale. See
Predefined Locales for details.
Return-Type: Usually Text. However, may be Number, if the result can be expressed as a number.
|
•
|
datevalue - This argument can be of type Number, and its the date/time value to format. Must contain the desired date/time represented as milliseconds since "Jan. 1st 1970, 00:00:00 GMT" (for example from the output of the functions CurrentMillis, SubscribeTimeMillis, and ToMillis).
|
|
•
|
formatpattern - This argument can be of type Text, and it specifies the format pattern to use to convert the milliseconds value in "datevalue" into the formatted representation.
|
|
•
|
localename - This argument can be of type Text, and its the name of a predefined locale. If specified, any locale specific text in "datetext" will be expected according to this locale. This argument is optional. Either you supply no further argument at all or you only supply this argument.
|
|
•
|
langcode - This argument can be of type Text, and its a lowercase two-letter ISO-639 language code specifying the language for the locale. For example, see here http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt for one list of the ISO-639 language codes. This argument is optional. Either you supply no further argument at all or you supply both the following this argument and the next.
|
|
•
|
countrycode - This argument can be of type Text, and its an uppercase two-letter ISO-3166 country code specifying the country for the locale. For example, see here http://www.iso.org/iso/country_codes/iso_3166_code_lists.htm for one list of the ISO-3316 country codes. If "langcode" and "countrycode" are specified, they are used to create a locale for the given language and country, and any locale specific text in "datetext" will be expected according to this locale.
|
ToDate(CurrentMillis, "MMM dd. yyyy")(formats the current date using the default U.S. locale)
ToDate(CurrentMillis, "MMM dd. yyyy", "Germany")
(formats the current date using the pre-defined locale for Germany)
ToDate(CurrentMillis, "MMM dd. yyyy", "de", "AT")
(formats the current date using a custom locale for language "de" =German and country "AT" =Austria)
Function: Returns the numerical value representing the date/time as parsed from the "datetext" argument, where the numerical value specifies the date/time in milliseconds since "Jan. 1st 1970, 00:00:00 GMT" (which can, for example, then be compared to the output of the functions
CurrentMillis and
SubscribeTimeMillis, or be used as input to
ToDate.
It generates a runtime error if there is a parse error. If you are unsure if a certain "datetext" and "formatpattern" can be parsed without an error, and you want to avoid this error, then use the companion function
IsDate to first check if the arguments can be parsed at all, together with the function
If (see the examples below.)
Note: For formatting purposes, LISTSERV Maestro will by default use the U.S. locale and the time zone of the server where the LUI component is running. Therefore, locale specific texts, like weekday names, names of months, and so on, will be formatted using the U.S. locale. Similarly, times will be formatted using the server's time zone. If you want to specify a different locale, you can do so with the optional parameter "localename" to choose a predefined locale or with the optional parameters "langcode" and "countrycode" to specify your own locale. See
Predefined Locales for details. If you want to specify the time as relative to a different time zone, you can include a time zone value in the date/time text.
|
•
|
datetext - This argument can be of type Text, and its the date/time text string to parse. Must contain the desired date/time in a textual format that can be parsed by applying the given format pattern.
|
|
•
|
localename - This argument can be of type Text, and its the name of a predefined locale. If specified, any locale specific text in "datetext" will be expected according to this locale. This argument is optional. Either you supply no further argument at all or you only supply this argument.
|
|
•
|
langcode - This argument can be of type Text, and its a lowercase two-letter ISO-639 language code specifying the language for the locale. For example, see here http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt for one list of the ISO-639 language codes. This argument is optional. Either you supply no further argument at all or you supply both the following this argument and the next.
|
|
•
|
countrycode - This argument can be of type Text, and its an uppercase two-letter ISO-3166 country code specifying the country for the locale. For example, see here http://www.iso.org/iso/country_codes/iso_3166_code_lists.htm for one list of the ISO-3316 country codes. If "langcode" and "countrycode" are specified, they are used to create a locale for the given language and country, and any locale specific text in "datetext" will be expected according to this locale.
|
ToMillis("February 22. 2004", "MMMM dd. yyyy")
(parses the given date using the default U.S. locale)
ToMillis("Februar 22. 2004", "MMMM dd. yyyy", "Germany")
(parses the given date using the pre-defined locale for Germany)
ToMillis("februari 22. 2004", "MMMM dd. yyyy", "de", "AT")
(parses the given date using a custom locale for language "de" =German and country "AT" =Austria)
If(IsDate(&FIELD;, "MMMM dd. yyyy"), ToMillis(&FIELD;, "MMMM dd. yyyy"), 0)
(checks if FIELD contains a date that can be parsed with the given pattern and the default U.S. locale, and if so, returns the numerical representation of this date, otherwise returns the default "zero (0)".)
Function: Checks if the merge field with the given name has a value or not. Returns "true" if the field has a value, "false" if not.
|
•
|
&MERGE_FIELD; - (type irrelevant): This argument must be the name of a merge field (complete with the starting "&" and the closing ";"). It can not be a constant value (a number, text, boolean or set).
|
If this function is used in a *Calc system drop-in of a job with recipients of type "Upload a Recipient Text File" or "Select Recipients from a database" (or target group recipients that base on one of these types), then you can use any of the merge fields that exist in this job as an argument for the
IsSupplied function. The function will then return "true", if the given merge field was empty either in the uploaded comma separated text file or in the corresponding database cell.
If however this function is used in a *Calc system drop-in of a job with target group recipients that are based on a dataset or a hosted recipients list, or if the function is used in the condition tree of such a target group, then you can not specify merge fields which are defined as "mandatory" or with the type "boolean", because such fields do by definition always have a supplied value. So using them with this function does not make sense, as the function would always return "true" for these fields anyway.
Function: This is an alternative method to retrieve the selected value of a single-select profile field, or the selected values of a multiple-select profile field. If such a profile field is included in the formula as a standard merge field (simply by supplying its merge field name &NAME;), then what you get is the currently selected entry name (for single-select) or a set of the currently selected entry names (for multiple-select). While this is usually the desired behavior, in special cases a different behavior may be required:
This is what is done with this function: It retrieves the currently selected secondary value as a return value of type Text (for single-select), or the set of currently selected secondary values as a return value of type Text Set (for multiple-select) of the specified single/multiple-select profile field. From which secondary column the values are retrieved is specified with the
secondaryColumnName argument.
Note: If this function is used to retrieve the secondary values of a multiple-select profile field, then the resulting set may have less elements than there are currently selected values for the profile field. This is because secondary values are not necessarily unique. So two or more of the selections of a certain subscriber could actually have the same secondary value. And since the return value of the function is a set (for multiple-select), and a set contains each element only once, those selections will result in only one entry in the resulting set.
Restriction: Can only be used in the derivation rule formula of a derived profile field, or in a formula in the condition tree of a "Dataset" or "Hosted Recipient List" target group, or in a "*Calc" system drop-in together with recipients based on such a target group. Will not be accepted in formulas for a different recipients type! Also, the specified profile field must be a single or multiple select field. Fields of other types will not be accepted. In addition, the specified
secondaryColumnName must be the name of a secondary column that is defined in the lookup table on which the profile field is based.
Important: Please remember that the secondary column is referenced in this function by name only. So if you use this function in a formula anywhere, and then later edit the name of the secondary column in the lookup table definition (or delete the secondary column from the lookup table), then this will not automatically change the formula too. The effect will be, that the formula becomes invalid, as it now references a non-existent secondary column. This in turn could for example cause mail job delivery errors (if the function is used in a *Calc formula, or in a target group condition tree), or prevent the re-calculation of a derived profile field value (if the function is used in the derivation rule formula of a derived field).
Therefore, take care when renaming or deleting secondary lookup table columns and, if necessary, also edit/repair any formulas that make use of such columns.
Return-Type: Text or Text Set
|
•
|
&MERGE_FIELD; - (single or multiple select profile field): This argument must be the name of a merge field (complete with the starting "&" and the closing ";") that corresponds with a single/multiple select profile field in the dataset or hosted recipient list. It can not be a constant value (a number, text, boolean or set).
|
|
•
|
secondaryColumnName - This argument can be of type Text. It must specify the name of a secondary column in the lookup table that is associated with the specified &MERGE_FIELD;.
|
The format of the date and time patterns must be specified for the functions “ToDate” and “
ToMillis” to convert a numerical date/time value (represented in milliseconds since “Jan. 1
st 1970, 00:00:00 GMT”) into a formatted output string or vice versa.
The pattern format described here applies to the formatting process, when a numerical date/time value is converted into a formatted text string, and to the parsing process, when a text string is parsed to convert it back into the numerical date/time value.
Important: For date/time formatting and parsing, by default the U.S. locale and the current time zone of the server where the Maestro User Interface (LUI) component is running is used. This means that if locale specific values (names of months, weekdays, era-designators, and the like) are required, they will be given as the U.S. locale values by default. Similarly, if a time is given, it will be formatted (or interpreted) as relative to the time zone of the server (although for parsing a specific time zone can be supplied). If the default U.S. locale is not desired, specify a locale in the “
ToDate” or “
ToMillis” function.
Date and time formats are specified by pattern strings. Within pattern strings, unquoted letters from ‘
A’ to ‘
Z’ and from ‘
a’ to ‘
z’ are interpreted as pattern letters representing the components of a date or time string (see below for details). Text can be quoted using single quotes <
'> to avoid interpretation. In a quoted text, the “double” single quote <
''> represents a single quote. All other characters are not interpreted; they are simply copied into the output string during formatting or matched against the input string during parsing.
The following pattern letters are defined (all other characters from ‘A’ to ‘
Z’ and from ‘
a’ to ‘
z’ are reserved). The letters are case-sensitive. The same letter has different meanings in its uppercase or lowercase version. Each pattern letter has a specific “presentation” in the created final string (during formatting) or in the parsed string (during parsing). For example, presentation types may be
Text,
Number,
Year or similar. More details about the presentations and their meanings follow below.
Notes: The value of “calendar week in year” and “calendar week in month” depends on the locale that is used. The locale determines the conventions about which weekday is interpreted as the first day of the week (usually “Monday” or “Sunday”) and under which circumstances a week that falls partially into one year (or month) and partially into the next, is interpreted as belonging to the one year (or month) or the other. The “weekday ordinal in month” indicates the ordinal number of the weekday of the given date/time in the given month. For the first Monday in a month, the ordinal is “1”, as it is for the first Tuesday, Wednesday and so on. For the second Monday in a month, the ordinal is “2”, and so on.
|
•
|
Text: For formatting, if the number of pattern letters is four or more, the full form is used; otherwise, a short or abbreviated form is used if available.
|
|
•
|
Number: For formatting, the number of pattern letters is the minimum number of digits, and shorter numbers are zero-padded to this amount.
|
|
•
|
Year: For formatting, if the number of pattern letters is two, the year is truncated to 2 digits; otherwise it is interpreted as a “Number” (see above).
|
For parsing with the abbreviated year pattern (“y” or “
yy”), LISTSERV Maestro must interpret the abbreviated year relative to some century. It does this by adjusting dates to be within 80 years before and 20 years after the current time. For example, using the pattern “
MM/dd/yy” on Jan. 1, 1997, the text “
01/11/12” would be interpreted as Jan. 11, 2012, while the text “
05/04/64” would be interpreted as May 4, 1964. During parsing, only strings consisting of exactly two digits will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that is not all digits (for example “
-1”), is interpreted literally. Therefore, “
01/02/3” or “
01/02/003” are parsed, using the same pattern, as Jan. 2, 3 AD. Likewise, “
01/02/-3” is parsed as Jan. 2, 4 BC.
|
•
|
Month: If the number of pattern letters is one or two, the month is interpreted as “Number”, if it is 3 or more, it is interpreted as “Text”. Therefore, if the month is interpreted as “Number” or “Text”, the applicable “Number”/ “Text” interpretation rules apply (see above). For example: 1 letter will be a “Number” that is not padded, 2 letters will be a “Number” that is padded, 3 letters will be a “Text” using the abbreviated form and 4 or more letters will be a “Text” using the long form.
|
|
•
|
General time zone: For formatting, the time zone is handled as “Text” if it has a name. If not, it is given as a GMT offset value in the format “ GMT[+|-]HH:MM”, where “ HH” is the hours between 0 and 23 (one or two digits, may be zero-padded to the left) and “ MM” is the minutes between 00 and 59 (always two digits, zero-padded to the left if necessary). For example, “ GMT+8:00”, “ GMT+08:00”, “ GMT-12:45”.
|
|
•
|
RFC 822 time zone: For formatting, the RFC 882 4-digit time zone format is used: “ [+|-]HHMM”, where “ HH” is the hours as two digits, between 00 and 23 (zero-padded to the left if necessary) and “ MM” is the minutes as two digits, between 00 and 59 (zero-padded to the left if necessary).
|
|
•
|
Time zone parsing: For parsing of a time zone, it does not matter if the format pattern specifies a “General time zone” or a “RFC 822 time zone”: In both cases, all three types of time zone specifications are accepted:
|
The following examples show how date and time patterns are interpreted in the default U.S. locale with the “U.S. Pacific Time” time zone. The given date and time are “
2001-07-04 12:08:56” local time in that time zone.
When specifying a locale to be used for date/time formatting in "ToDate" or for parsing in ToMillis, you can either specify the specific ISO codes of the desired country and language (see "ToDate" and "ToMillis”), or you can simply specify one of the following predefined locale names, which stands as a shortcut for the given language and country combination..
However, if the text itself is supposed to contain the quote character (") anywhere, special rules need to be obeyed. This is because if the quote was to be included just like that, LISTSERV Maestro would interpret it as the closing quote of the text and would try to interpret the rest of the text as part of the formula - which will almost always cause a syntax error, or at least give undesirable results.
Therefore, any quote character in the actual text must be escaped by "doubling" it. If you want to include a quote in the text, you must type two quotes, one right after the other, with no space between them ("").
